/*
 * Copyright:  2018 smarabbit studio.
 *
 *  Licensed under the Confluent Community License; you may not use this file
 *  except in compliance with the License.  You may obtain a copy of the License at
 *
 *  http://www.confluent.io/confluent-community-license
 *
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
 *  WARRANTIES OF ANY KIND, either express or implied.  See the License for the
 *  specific language governing permissions and limitations under the License.
 *
 *  @作   者： 黄开晖 (117227773@qq.com)
 *  @日   期:  2021年5月23日
 */
package com.massyframework.beanskin.util.classloading;

import java.io.IOException;
import java.net.URL;
import java.util.Enumeration;

import com.massyframework.beanskin.ModuleIdentifier;

/**
 * {@link LocalResourcesPath},指向本地资源路径.
 * 
 * <p>
 * 对于ModuleClassLoader而言，资源被划分为三部份：
 * <ul>
 * <li>自身掌握的资源
 * <p>
 * 自身掌握的资源是构造方法中传入的URLs，每个ModuleClassLoader都由LocalClassPath封装并管理本地资源的查找。
 * </li>
 * <li>
 * 所依赖的其他模块类加载器的本地化资源。
 * <p>
 * 通过其他模块化类加载的LocalClassPath可直接定位查找对应资源.
 * </li>
 * <li>parentClassLoader中的资源
 * <p>
 * 在以上两种都无法找到的情况下，交由parentClassLoader处理。
 * 正常情况下，所有SelfFirstClassLoader的parentClassLoader都相同，指向应用程序的类加载器。
 * </li>
 * </ul>
 * @author huangkh
 *
 */
public interface LocalResourcesPath extends ModuleIdentifier {
	
	/**
	 * 根据{@code name}查找类定义<p>
	 * 
	 * @param className {@link String}, 类名
	 * @param excludeLoader {@link ClassLoader}, 需要排除的类加载器,可能为null。
	 * @return {@link Class}, 类定义
	 * @throws ClassNotFoundException 类没找到时抛出例外
	 */
	Class<?> findClass(String className, ClassLoader excludeLoader) throws ClassNotFoundException;
	
	/**
	 * 根据{@code name}查找首个符合的资源
	 * @param name {@link String},资源名称 
	 * @param excludeLoader {@link ClassLoader}, 需要排除的类加载器,可能为null。
	 * @return {@link URL},资源不存在则返回null.
	 */
	URL findResource(String name, ClassLoader excludeLoader);
	
	/**
	 * 根据{@code name}查找所有符合的资源
	 * @param name {@link String},资源名称 
	 * @param excludeLoader {@link ClassLoader}, 需要排除的类加载器,可能为null。
	 * 	如果搜索路径中包含ClassLoader, 可以跳过。
	 * @return {@link Enumeration}
	 * @throws IOException io读写发生例外
	 */
	Enumeration<URL> findResources(String name, ClassLoader excludeLoader) throws IOException;
}
